AN IN-DEPTH LOOK AT... SERIES
A SUPPLEMENT TO THE NUTTING MANUAL FOR THE BALLY/ASTROCADE HOME COMPUTER SYSTEM
Version 0.0

INTRODUCTION

I recall thinking way back around 1980, when I purchased my Bally Basic, that I was going to be able to create programs similar to the Bally Videocades. Boy, was I really surprised after playing around with the Basic language. I discovered I couldn't create "cartridge quality" games using this language. I then found out that the Bally Videocades were written in machine language. So, I decided to learn how to write programs in machine language, which prompted me to buy various written materials on the subject. I purchased a copy of Peek N' Poke, the Bally on-board subroutines, a disassembled listing of Bally ROM, a Z80 users manual and a book on Z80 assembly language programming. By studying examples of ML routines in my Cursor/Arcadian issues and the above written materials that I purchased, I eventually learned how to create programs in ML.

Anyone interested in writing programs for their Bally/Astrocade in ML or programming in assembly language will eventually learn about what is commonly referred to as the "Nutting Manual". This manual is packed with programming information for the Bally/Astrocade. It has a very nice system description on pages 81–107. The manual even includes an assembled source code listing for the 8K ROM chip on the Bally/Astrocade motherboard. From a programming viewpoint, the manual does provide details on the ROM's UPI processing and on-board subroutines, but does not provide examples so the reader can acquire thorough understanding as to how the UPI and subroutines function. The details it does provide, at times, is insufficient and can leave the reader desiring more info.

The intent of this "An In-Depth Look At ..." series is to supplement the Nutting Manual providing missing information plus stressing ML and assembly language program examples. The series will progress towards the presentation of programs with complex graphics and motion. Programs will also include extensive programming comments.

This series is not intended to teach the reader how to create ML programs or program in assembly language. Rather, the series will show how the on-board ROM subroutines can be used to display graphics, move nonblinking graphic patterns around the screen and perform many other tasks. This series will assume that an interested user, desiring to learn how to create programs in ML or program in assembly language, will read and study additional sources to supplement their study of the series example programs in each lesson.

Early on in the series, the program examples will be simple and will allow the beginner, with the help of outside Z80 CPU programming sources, to get started in writing routines to display and move graphic patterns. The extensive program comments should help the beginner to grasp fundamental programming techniques. As more examples are worked and studied, the beginner hopefully, will become comfortable with the ML and assembly language, which will provide faster program execution and improved graphics compared to the Bally/Astrobasic language. So, have patience with this series, work and study the lesson program examples. Soon, you will be experimenting, programming in assembly language and writing ML programs for the Bally/Astrocade computer system.

SERIES LESSONS DESCRIPTION (LESSONS 1-20)

The first few lessons will cover the setup of the TV screen parameters typically required prior to the execution of the main program.

The magic RAM will then be examined by working various magic functions. Graphic routines will be used, without the aid of any UPI subroutine call, providing the reader a look at how graphic patterns are actually displayed on the TV screen. This approach will also show the reader how to write a graphic pattern at maximum execution speed. Maximum speed will be achieved because there will be no UPI processing.

The Z80 restart instruction will be introduced and the on-board User Program Interface (UPI) will be discussed thoroughly. The same magic functions examined previously will be repeated, but this time using an UPI on-board subroutine call.

The optional user defined UPI subroutine call will be detailed plus how to use the UPI for multiple subroutine calls.

Following the UPI lessons will be a lesson on moving nonblinking graphic patterns around the screen.

All of the above will be presented in about 20 lessons. It will take around 40 more lessons to cover the majority of the remaining on-board subroutines, the application of screen interrupts and the on-board power up routine. The 8K ROM on the Bally/Astrocade is packed with 57 subroutines usable for demos, games and more. That is a lot of lessons to cover, but is a necessity if you want to learn how to create a commercial grade demo or game with minimal custom subroutines. Think of all of these lessons as pieces of a picture puzzle. The pieces have to be examined to fit them together. Once these series lessons are presented, then it will be time to use the lessons learned and begin showing how complex demos or games can be created. This series will indeed be ongoing. MCM Design is hoping the series will generate some reader interest resulting in the creation of some new demos or games that cannot be matched using the Bally or Astrobasic language.

TERMINOLOGY: MACHINE LANGUAGE OR ASSEMBLY LANGUAGE
WHO CARES?

A language is a means of communication. There is a spoken language, a written language and in the case of computers, a digital language. A microprocessor (CPU) cannot think and must be communicated to and told what tasks to perform. One way it is told to perform tasks is by wiring it to computer hardware such that specific logic signals at specific times inform the CPU to perform various tasks. The other way is through instructions using a data bus. All Bally/Astrocade computer systems utilize the Zilog Z80 CPU. The Z80 utilizes an 8–bit data bus to receive instructions from ROM or even RAM. There has to be a starting point for the Z80 to receive instructions, which is at the ROM address 0000H. When you press the system reset button, you force the Z80 to begin receiving instructions at that address 0000H. The Z80 must fetch every instruction, interpret them, then execute them. The instructions are in the form of 8–bit binary codes. The codes consist of bytes, each byte consisting of 8 bits that are either at a logic 1 or a logic 0. An instruction coding can be more than 1 byte long, depending on what task the instruction dictates. This form of communication to a CPU is all it understands.

So, the CPU is directed to execute instructions using a digital language which is called the Machine language. This language is considered a low-level language. Because the Machine language is coded, it is difficult for anyone to read this language to determine what is being communicated to the CPU. So a higher level language is used, which is easier to read, to tell the CPU what tasks to perform. This higher level language has to utilize some kind of interpreter to communicate (speak) to the CPU using the Machine language.

The next level up from Machine language is Assembly language. Assembly language must be very specific and requires the use of abbreviated instructions called Mneumonics. Mneumonic instructions are much easier to read than machine coding. The Mneumonic instructions are then interpreted (converted) to Machine language using an Assembler, which is part of the AL software.

There is also another form of programming software referred to as a Machine language monitor. With this software, the programmer does NOT start off programming in Machine language. That would be very difficult. Instead, the programmer must write the program using Mneumonics (AL instructions). Then, the programmer must take on the role of the interpreter and manually convert the AL instructions to ML coding (instructions).

Timewise, it may actually take less time to create and load a very short program for execution using a Machine language monitor instead of using AL software. That's assuming debugging is not required. However, for longer programs, the choice is clear. Assembly language software, like Zmac, will save you time and work to create, debug and run a program compared to a Machine language monitor.

So, is MCM Design being fussy to point out the distinction between ML and AL? Perhaps. Who really cares about the distinction? Good question. Has MCM Design ever used the terminology ML and AL synonymously? Guilty as charged.

SERIES USER REQUIREMENTS

This series is intended for anyone interested in learning how to utilize the many on-board ROM subroutines and applying various programming techniques to create demos, games or other programs which the Astrobasic language is not capable of producing. Experienced assembly language programmers will likely find info in this series that is not documented in the Nutting Manual or other Bally/Astrocade sources.

The series will start off with lesson examples requiring the use of Bit Fiddler's Machine Language Monitor (MLM). MLM is easy to use and is a good choice for very short programs. Once you understand how to use MLM to load(write) bytes of data into memory, you simply load the lesson example program bytes into RAM, then use MLM to call the program that you just loaded. That's all there is to it.

Later on in the series, when a program in a lesson example gets more complicated and long, it will be time to switch over to the ZMAC assembler, so the programs can be saved plus run as an emulated game cartridge. This switchover will allow programs to be up to 8K bytes in length. Details will be provided later in the series when this program switchover occurs.

The following is a listing of the series requirements to execute a lesson example program and understand how the program works.

1. Bit Fiddler's MLM is required to load and call short ML program examples. If the series user has the MLM programming cartridge or an Ulti-Multi cartridge with MLM on it, then that MLM can be run on a Bally/Astrocade console without any additional hardware required.

MLM running on a console requires the use of a 24 button keypad overlay. If the user does not have the actual MLM overlay, an extra overlay, such as the Scribbling overlay can be relabeled by trimming down with a scissors, multi-use labels, which are available at a grocery or drug store. A picture of the required MLM overlay is posted on the BallyAlley.com website in the Pictures/Keypad Overlays section.

http://www.ballyalley.com/pics/keypad_overlays/full_size/MLM%20Overlay%20(150%20dpi).jpg

If the user does not have an extra overlay, a make-do overlay can be created by cutting 9 small pieces from a TV dinner package or equal, sized to fit the keypad. Lay each piece down on the keypad, one at the time, using masking tape or multi-use labels to hold the pieces together. Then, label the constructed overlay using multi-use labels. Occasionally an overlay is up for sale on eBay. Enter "Bally Astrocade" and also "Bally Computer" when using the eBay search box. You might luck out and see an overlay for sale there.

2. If you do not have the MLM on a cartridge, you can run an emulation of the MLM on MAME's Astrocade emulator. You will have to set up the emulation on your computer. There is a MAME emulation set up video archived on the Bally Alley website in the Videos/Astrocade Emulation Video section.

http://www.ballyalley.com/astrocade_videos/Astrocade_Emulation_Videos/Astrocade_Emulation_Videos.html

This tutorial video is very detailed. You may find it necessary to pause the video so you can take notes. The video is not intended to cover every aspect of the MAME emulation set up. For example, you might want to locate the emulator in a different location or you may want to access the emulator differently than shown on the video. The video sets up the emulation on a Windows 7 operating system. You may have to consult other sources such as WikiHow or YouTube for your particular application. You should also turn on your computer's file extensions. If your computer's file extensions are off, the video may be a little harder to follow. The video also demonstrates how to load into your computer, a large collection of Astrocade cartridge ROMs including MLM, to be accessed and run by the Astrocade emulation. Most of these ROMs will run on the emulator. Many of the ROM user instructions are also posted on the Documentation/Cartridge Manuals section.

http://www.ballyalley.com/cart_manuals/cart_manuals.html

To run MLM using the Astrocade emulator, see below "Running MLM On MAME's Astrocade Emulator". You will need to reconfigure your keyboard layout for MLM. See below "How To Reconfigure The MAME MLM Emulator User Key Layout".

3. The short lesson examples will utilize the MLM, so it will be necessary to learn how to use the MLM. The MLM Users Manual is archived on the Bally Alley website in the Machine Language/Astrocade ML Docs section.

http://www.ballyalley.com/ml/ml_docs/mlm_docs.pdf

You will not need to understand every MLM feature. Since the short lesson examples will already be set up for use with the MLM, it will simply be a matter of loading the program data bytes into screen RAM, listing the program to check for typos, then calling the program to execute it. The more challenging part will be to understand how the program functions. Extensive program comments will be included with the examples, where needed. However, the user may have to consult outside sources for further understanding.

There is also available, a 4-part video tutorial explaining how to use the MLM to program a Bally/Astrocade home computer to execute ML programs. This video tutorial is also posted on the Bally Alley in the Videos/Programming section. The final Part 4 covers using the emulation of MLM with the MAME Astrocade emulation.

https://ballyalley.com/astrocade_videos/Programming_Videos/Programming_Videos.html

4. The Bally Alley offers an abundance of reading sources relating to the programming of the Z80 CPU, which is sometimes referred to as a microprocessor. All Bally/Astrocade motherboards utilize a Z80 CPU to execute programs and perform other tasks. For the beginner desiring to learn how to program a Z80, the info in these sources can be overwhelming. Since the early lesson examples will be fairly simple and will include program comments, MCM Design recommends the beginner follow the directions A thru E below for a quick start prior to working and studying the lesson examples. These directions below should provide enough info to get started studying ML and AL programs to see how Z80 instructions execute. The majority of the Z80 programming sources archived on the Bally Alley are located in the Machine Language/Z80 ML Docs or the Astrocade ML Docs sections. Note that some of these sources include the mixing of machine language routines along with the Astrobasic language, which does not apply to this "An In-Depth Look At... " series. There will be no use of the Astrobasic language in any of the lesson examples in this series.

A. BROWSE through the "Bally System Description" in the Nutting Manual, pages 81-107. A lesson in this series may reference a particular topic in this system description.

http://www.ballyalley.com/ml/ml_docs/Bally_System_Description-Searchable.pdf

B. READ the "Astrocade Machine Language Programming Tutorial", by the Bit Fiddler's Corner, parts 1,2 and 3 only. This doc is an introduction to ML programming.

http://www.ballyalley.com/ml/ml_docs/Bit%20Fiddler/Bit%20Fiddler's%20Corner%20(1983)(Andy%20Guevara).pdf

C. READ the "MLM Users Manual" by Bit Fiddler's, page 2–1 thru 2-6. This is another intro to ML programming.

http://www.ballyalley.com/ml/ml_docs/mlm_docs.pdf

D. READ the Zilog "Z80 Microprocessors, Z80 CPU User Manual", UM008011-0816, C2016, pages 1 thru 4. The page numbers indicated to read are the manual's page numbers NOT the Adobe reader page numbers. This info is an introduction to all the available internal Z80 CPU registers, all of which can be programmed to perform various tasks.

https://ballyalley.com/ml/z80_docs/Z80%20Family%20CPU%20User%20Manual%20(Aug%202016)(Zilog)(UM008011-0816).pdf

E.PRINT OUT in the same Zilog manual indicated above in D, the listing of the available Z80 instructions on pages vi thru x. This listing is part of the Table Of Contents. The listing points to the page number of the indicated Z80 instruction (Mneumonic) where that particular instruction is detailed. This listing is arranged not in alphabetical order, but in 8 groups. The 8 groups are listed on page 32.

This same manual includes the complete Z80 instruction set, detailing the many available instructions, and is listed on pages 69 thru 316. Reference also the "Instruction Notation Summary" on page 39.

When you initially use this list of instructions to look up details on a particular Z80 instruction, interpret the details as indicated below.

i. The entire Z80 Mneumonic is shown on the top of the page.

ii. This manual refers to the first portion of this Mneumonic as the "opcode".

iii. The remainder of the Mneumonic is referred to as the "operand".

iv. The word description details what the Z80 instruction accomplishes. Ignore any details just below this word description.

v. The operation detail attempts to describe the action of the Z80 instruction.

vi. Within the operand detail, you will see a diagram(s) indicating the 8 bit byte(s) of coding that the Z80 must fetch from ROM to execute successfully this instruction. This coding is referred to as the Z80's operational coding and may be more than one byte long. You can ignore the coding detail for now.

vii. An example description attempts to expand upon the above word description.

viii. Finally, a detail describes what bits, if any, in the Z80 F register are affected when this instruction is executed.

Use some of the instruction details to help you figure out what a Z80 instruction in a lesson example program accomplishes. You may eventually want to print out this complete Z80 instruction set unless you can purchase this manual somewhere. There are other sources available that include details on the complete Z80 instruction set. This particular Zilog manual includes some nice details. Some other sources may provide overwhelming detail for a beginner. If you are considering purchasing or printing another source with the complete instruction set, do a comparison to choose the documentation that suits your needs best.

5. Once you become reasonably comfortable in understanding how the Z80 instructions execute in the lesson example programs early on in the series, you will eventually need to read and study additional docs archived on the Bally Alley, to further your understanding of ML and AL programming. When you browse through or read these docs, your emphasis at first should be WHERE within the doc a particular topic is discussed. List the topics on your personal topics page(s) and index (point) to where, within the doc, the topic is discussed. This way, when you are studying an example program, you can quickly locate the discussed topic to help you understand portions of the example program. Besides understanding how Z80 instructions operate, comments made in the example programs may indicate to you to study a particular topic which you need to understand.

Topics that you should look for and note, for future reference, are listed below. Note the location of these topics within the docs that you have read because eventually you may have to apply your understanding of these topics in a lesson example program.

A. The difference between a decimal, binary and hexadecimal (hex) number.

B. How to convert a decimal number to a hexadecimal number.

C. How to convert a hexadecimal number to a decimal number.

D. How to add 2 binary numbers.

E. How to convert a positive binary number to a negative binary number using a 2's complement procedure. This will allow the converted negative binary number to be added instead of subtracted from some binary number.

Note: When using ML, you might be required some day to use your understanding of A thru E above to manually convert some particular number for use with a ML program.

F. Types (groups) of Z80 instructions, each group having a specific purpose. Acquaint yourself with the various groups of instructions.

G. The purpose of each flag in the Z80 F (flags) register.

H. The compare instruction.

I. Conditional instructions like the conditional jump, call and return instructions. These instructions execute dependent on a respective flag being set or reset in the F (flags) register. It is important to understand how to read the instruction Mneumonic.

J. How to compute the jump code that follows a jump relative (JR or DJNZ instruction) opcode. The understanding of this topic is necessary when working with ML programs. Assembly language software will make this computation for you.

K. AND, OR, XOR logic functions.

L. The purpose of the stack area in screen RAM and the execution of PUSH and POP instructions.

Below are two of MCM Design's recommended "intermediate level" docs, which are archived on the Bally Alley, which you should read.

"Introduction To The Z80 Assembler" by James Hollidge, which covers:
Decimal, binary and hexadecimal numbers
The Z80 registers
Z80 instructions intro
Binary addition and subtraction
The operation of the flags in the Z80 F register
The AND, OR, XOR logic functions
The Z80 stack area (in RAM)
Note: This doc covers 2 topics which will likely be hard to follow because of the author's choice of numerical representations. The 2 topics are:
Binary vs Decimal vs Hexadecimal
Addition and Subtraction

http://www.ballyalley.com/ml/z80_docs/z80_docs.html

The Zilog "Z80 Microprocessors, Z80 CPU User Manual", UM008011-0816, C2016.
Pages 32-64, presents an overview of the types (groups) of Z80 instructions. There are some typos in this presentation. Figure 37, on page 47, has the wrong diagram. The 3 byte opcode operand sequence should be 11 59 06.

Z80 opcode tables for the instructions are also included in these pages. The tables typically show the "source", that part of the Mneumonic that follows the comma, horizontally across the table. That part of the Mneumonic that precedes the comma, sometimes referred to as the "destination", is shown running down the left side of the table.

Other sources of documentation may list Z80 opcodes along with the complete alphabetical listing of the Z80 Mneumonics. An alphabetical listing is much easier to read than a bunch of tables. This kind of listing is available for example in "The Undocumented Z80 Documented" by Sean Young, chapter 10, pages 42 thru 47. If you decide to experiment and create some ML programs of your own for use with MLM, you should print out a 2nd set of complete Z80 Mneumonics with the opcodes, so you can use this 2nd listing as an opcode typo check.

Pages 65-69, details the operation of each flag within the Z80 F (or F') Flags register. Some Z80 instructions will execute, then set or reset a particular flag in the F register allowing a program to check the status of that flag and then respond accordingly to that status.

Note: The page numbers indicated above are the Zilog manual pages NOT the Adobe reader pages.

https://ballyalley.com/ml/z80_docs/Z80%20Family%20CPU%20User%20Manual%20(Aug%202016)(Zilog)(UM008011-0816).pdf

6. Some of the ML docs on the Bally Alley are advanced reading. Of particular interest is the doc "The Undocumented Z80 Documented" by Sean Young. This doc may include information you typically may not find in other Z80 ML sources. Included in the doc are extra undocumented Z80 instructions. There are 2 listings of the complete Z80 instruction set listed by Mneumonics and also by opcodes. The extra instructions are marked with an asterisk.

ABBREVIATIONS AND DEFINITIONS

Z80	A reference to the Zilog 40 pin Z80 CPU (microprocessor) which is utilized by all Bally/Astrocade motherboards to execute programs and perform other tasks.

NM	An extensive documentation commonly known as the Nutting Manual detailing the Bally/Astrocade home computer system.

Bit	A binary digit representing a logic 0 or logic 1. The bit is typically associated with bytes of memory or the internal Z80 CPU data registers.

Byte	A byte consists of 8 bits normally labeled as bits 7,6,5,4,3,2,1 and 0. Bit 0 is labeled as the right most bit and bit 7 as the left most bit in a byte. A byte is usually referenced to an address (location) in memory but can also simply refer to just 8 bits of data. One Kilo byte (1 KB) of memory equals 1024 bytes.

Nibble	A nibble is 4 bits of data. There are 2 nibbles in a byte.

LSB	The least significant bit in a byte which is bit 0. You can also think of a nibble as having a LSB, bit 0 or bit 4 depending which nibble you are looking at.

MSB	The most significant bit in a byte which is bit 7.

K	K = Kilo = 1000. In computer terminology however, 1KB = 1024 bytes. A Z80 CPU can directly address up to 64KB (65,536 bytes) of memory.

Word	A word consists of 2 bytes (16 bits).

ROM	Read Only Memory. The data in ROM cannot be changed. The Bally/Astrocade motherboard provides 8K bytes (8KB) of ROM addressed 0000-1FFFH. An extra 8KB is available for use as ROM in a cartridge and is addressed 2000-3FFFH.

RAM	Random Access Memory can be changed by the Z80 CPU. The only RAM on a Bally/Astrocade motherboard is screen RAM, which is used for the TV display and is addressed 4000-4FFFH. Screen RAM is also used to save variables or data for on-board ROM subroutines or other purposes. The Z80 also uses this RAM for the stack area. All of this saved data is normally located at the bottom of the TV screen and is hidden from view.

LO	LO = Low Order as in a low order byte.

HO	HO = High Order as in a high order byte. Using the hex number 40A0H as an example, A0 is the low order byte (or address if the number represents a memory address) and 40 is the high order byte (or address).

Pixel	Pixel = picture element. A pixel is a tiny dot (square) displayed on the TV screen. The Bally/Astrocade can only display a pixel in one of four possible colors. It takes two bits of screen RAM to define one pixel color. There are four pixels in a screen RAM byte. The TV display is 40 bytes wide by 102 lines high. So, the resolution in a Bally/Astrocade TV display is 40x4x102 = 16,320 pixels. Screen RAM is 4KB = 4096 bytes. The TV display utilizes 40x102 = 4080 bytes. So, there are 4096-4080 = 16 bytes not used for the TV display. These 16 bytes are referred to as the scratchpad. See the "System Description" in the NM for additional info related to the TV display.

ML	ML = machine language

MLM	Bit Fiddler's Machine Language Monitor (software used to program in ML).

Decimal	A number that you normally work with consisting of 1 or more digits. Each digit can be 0 or 1 thru 9.

Binary	A number represented only by zeros and ones, where 0 = logic 0 and 1 = logic 1.

Hexadecimal A hex number is a simpler means of representing a binary number. It is similar to a decimal number, in that each digit is extended to a possibility of 16 numbers as 0,1 thru 9 or A,B,C,D,E,or F. One digit can be represented by a nibble (4 bits) and two digits by a byte (2 nibbles or 8 bits). So, with the Z80, two bytes (16 bits) can be represented by any 4 hex digits 0000 thru FFFF and one byte by 2 hex digits 00 thru FF. A two or four digit number followed by a capital H indicates the number is a hex number.

n	A single byte (8 bit) hex number.

nn	A two byte (16 bit) hex number.

r	An 8 bit Z80 register.

rr	A 16 bit Z80 register.

PC	The internal Z80 program counter that points to the next Z80 instruction that is to be fetched and executed by the Z80.

Stack	An area in RAM that is used to save data freeing up Z80 registers for various tasks. Data is saved in the stack and retrieved from the stack by executing PUSH and POP instructions.

SP	The stack pointer, an internal 16 bit Z80 register, always points to the top of the stack (a RAM address). For example, if a program is currently utilizing a 16 byte stack area from 4FBE to 4FCDH, the SP register would be currently pointing to the top of the stack area, address 4FBEH (which is actually the lower RAM address). Think of the Z80 stack area as a stack of poker chips, where each chip represents one byte (8 bits). The SP points to the top poker chip. PUSH instructions increase the size of the stack area (adds more poker chips to the stack) and POP instructions decrease the stack area (takes away poker chips from the stack). The programmer has to keep track of where the SP is pointing when using PUSH and POP instructions in order to save and retrieve the correct data from the stack.

Flags	There are flags in the Z80 F register which are set or reset depending on the last Z80 instruction that affects any of the flags after its execution. Various Z80 instructions allow a program to test a particular variable by examining one of these flags and then respond by executing, for example, a particular jump, call or return instruction. Also, some of the on–board subroutines utilize specific bits in the bottom of certain screen RAM addresses as "flags" for specific purposes.

Opcode	Every Z80 instruction utilizes one or more bytes of ROM as the instruction's entire operational coding. Docs typically break down the entire operational coding for a Z80 instruction with the first one or two bytes labeled as the opcode and the remainder of the coding, if any, labeled as an operand or displacement value. Docs also label the one or more bytes of operational coding as an "opcode" or as "opcodes". After the Z80 fetches the operational coding from memory, it then interprets the codes so it can execute that instruction.

T-State (T-Cycle) A T-state is the time it takes the system clock, input to the Z80 at its pin 6, to complete one cycle (one period of time). The Bally/Astrocade clock frequency is about 1.7898 MHz (cycles per second theoretically). This clock can be measured with a frequency counter or logic analyzer. The clock cycle period is T = 1/F, where F = the clock frequency. This time T is referred to as a T-state (or T-cycle). So, one T-state = 1/(1.79 x 106) = 560nsec (n = nano = 10-9). A Z80 instruction takes 4 or more T-states to execute, depending on how many bytes of opcode the Z80 has to fetch plus the actual time it takes to interpret and execute the instruction after the fetch cycle is completed. You can look up in the Zilog Z80 technical manual or equal, the total amount of T-states each Z80 instruction takes to execute completely. This info allows the programmer to determine or calculate the theoretical time it takes to execute a number of Z80 instructions for a specific purpose, for example, a time delay. The Z80 on the Bally/Astrocade can, assuming the execution of only 4 T-state instructions, execute (1.79x106)/4 = 447,500 instructions per second.

RUNNING MLM ON MAME'S ASTROCADE EMULATOR

1. After you installed the Astrocade emulator along with its cartridge ROM collection, look for the MAME Astrocade emulator startup "application file". For the Windows operating system, it is probably labeled "mame64.exe" preceded by a custom blue character M.

2. Double left-click on this file. A Bally ROM menu should appear displaying the 3 motherboard ROM versions available for emulation.

3. Double left-click on one of these ROM versions.

4. A menu of the cartridge ROM collection should appear. Move down the menu to "Machine Language Manager" by left-clicking the down pointer 4 times.

5. Double left-click on "Machine Language Monitor". The screen will clear and a small system specs window will pop up.

6. Press any key on your keyboard and you will get the MLM startup screen.

7. Confirm MLM is running by pressing any of the keys 0 thru 9 on the main keyboard several times. You should see that number written on the screen.

8. The default user keys for MLM are spread out around the keyboard. The Bally Alley documents the MLM emulation default user keys in the Pictures/Keypad Overlays section.

http://www.ballyalley.com/pics/keypad_overlays/mlm_keypad_emulation.jpg

You need to reconfigure the MLM keyboard layout so the user keys are easier to find. See the reconfigure procedure below to change the user key layout that works best for you.

9. If so desired, to return to the Bally menu described in above step two, simply press your keyboard escape (ESC) key.

HOW TO RECONFIGURE THE MAME MLM EMULATOR USER KEY LAYOUT

1. Run the MLM emulator to display its startup screen, then press your keyboard tab key.

2. The tab menu will pop up. Point to "Input (This Machine)" and double-left click this selection.

3. An inputs menu will pop up. Left-click the down pointer twice to move to the bottom of this menu. Note that there are 24 rows of characters between the "Paddle 4 Analog Inc" input parameter and "Return To Previous Menu". These rows represent the 24 button keypad inputs for the Bally/Astrocade console. The very first character in each row is the standard label on the console's keypad. Note that the third row shows a slash to indicate it is the division key. The character(s) and information to the right of the first character in each row represents what you would see on a Bally/Astrobasic overlay, which will fit over the 24 button keypad. At the very right of each row is the current input setting for your computer's keyboard.

You can change any of these 24 keypad input settings as follows:

4. Use your keyboard up/down key to point at (highlight) the keypad button you want to reconfigure (change).

5. The current input setting must be deleted, unless you want to add your new setting to the current setting. Avoid double left-clicking the mouse to change the input, because you may experience setting problems.

Press the delete key so the input setting reads "None". If this doesn't work, press the enter key, then the escape (Esc) key to display "None".

6. Press the enter key to display left/right pointers.

7. Press the desired key on your keyboard that you want this input reconfigured to. That new key should now be displayed confirming your change request.

8. Repeat steps 4 thru 7 to reconfigure any other key(s).

9. To exit the inputs menu, point to "Return To Previous Menu" and double left-click it.

10. The tab menu will then appear. Do the same as step 9 to return to the MLM emulation.

MCM Design reconfigured its Windows 7 keyboard for the MLM emulation as indicated below. Maybe you will like this layout. Try it or use your variation of it. 

Do not change the keys 1 thru 9 and 0.
Use the QWERTY keys as A B C D E F respectively. Relabel these 5 keys by taping down a 1/2" X 5" paper with the new labels on top of the QWERTY keys, sized to fit. Yes crude, but effective. Also,

USE	AS MLM
KEY		KEY

Left		ADDR
Up	READ
Down	LIST
Right	CALL
Enter	WRITE
Numeric *	*
Numeric +	REG
Insert	INSERT

F3 remains as the system reset button.
P remains as Pause.

The Inputs Menu reconfiguration should appear as indicated below.
The Astrobasic overlay char/info is omitted below for simplicity.
The "MLM Overlay" column listed below is for reference only. You will not see this column on your screen display.

24 Button	MLM		Reconfigured
Keypad Char	Overlay		For Windows 7
				Keyboard

.	         WRITE		Enter
%              CALL		Right
/		   REG		Num +
x		   LIST		Down
-		   INS		Insert
+		   READ		Up
=		   ADDR		Left
down		   F			Y
CH		   C			E
9		   9			9
6		   6			6
3		   3			3
CE		   *			Num *
up		   E			T
MS		   B			W
8		   8			8
5		   5			5
2		   2			2
0		   0			0
C		   D			R
MR		   A			Q
7		   7			7
4		   4			4
1		   1			1

Note: Use the same procedure as indicated above in steps 4 thru 8 to change any of the player 1 (P1) input parameters at the top of the Input Menu's list if you want to play some ROM cartridge games. If you are using a Bally hand controller with an Astro-daptor, refer to "Setting Up The Astro-daptor With Mame" on the Bally Alley/Emulation/Mame,Mess section.

THE LESSON EXAMPLE PROGRAMS IN THIS SERIES

As mentioned previously, this series is intended for the beginner interested in learning how to program the Bally/Astrocade by writing programs in machine language or assembly language. Those that have some experience in ML or AL, but need tutorials as a supplement to the Nutting Manual, to make full use of the on-board subroutines, may eventually find the series beneficial.
 
The example programs for many of the lessons in this series will be set up for use with Bit Fiddler's Machine Language Manager (MLM). Why? From a beginner's viewpoint, trying to read a ML or AL program listing generated by AL software, like the Zmac assembler, may be undesirable because of all the additional labeling and such that comes with assembly language software.

Learning how to use MLM is much easier than learning how to use AL software. Using Bit Fiddler's MLM allows MCM Design to list the short example programs with a minimum amount of labeling. This way, the beginner can focus quickly on the program Z80 Mneumonic instructions, the program comments and also the Z80 operational coding used for the Z80 Mneumonics.

The second reason for using MLM is that because it is so easy and fast to change data bytes in a program, you can play around with the program and make some changes, experimenting with it to increase your understanding or just have fun experimenting.

So, to those who have experience in assembly language and insist only on using AL, MCM Design recommends you read the lessons and also look at the MLM example programs, because you may find something there that is not documented in the Nutting Manual, the Bally Alley or the Better Bally Book. As an option, you could use MLM to run an example program to confirm the info is accurate. This series will eventually switch over to the Zmac assembler when the example programs start getting more complicated and long.

MLM LESSON EXAMPLE PROGRAMS

The example programs, usually subroutines, will typically begin at 4E10H. So, after you manually enter the program into screen RAM, you then enter 4E10, press the ADDRESS key, then press the CALL key to execute the program.

Labeling and memory addresses will be kept to a minimum in the program layout to help the beginner focus on the Z80 Mneumonics (instructions) and any additional data bytes required to execute a program.

The program will list the Mneumonics, an abbreviated form to identify what specific Z80 instructions are executed, in the center of the program layout.

To the left of the Mneumonics, the actual Z80 operational coding (opcodes with necessary operands) and other required data bytes like tables, graphic patterns, etc. will also be listed. This data, that must be loaded into screen RAM, is what the Z80 actually fetches, processes or interprets for execution.

To the left of the Z80 operational coding and other data bytes will be screen RAM addresses, showing where a particular data byte resides (is stored). These RAM addresses will be listed typically every 16 bytes to reduce clutter. Addresses will also appear at the beginning of routines, subroutines, tables, etc. and will be labeled with the name that is used within the program. Note that each RAM address listed contains only one byte of data. You may see additional names (labels) for use with program loop backs or jumps.

To the right of the Mneumonics or inserted above a group of Mnemonics will be program comments. Left and right brackets may precede and follow a comment on the right. These left/right brackets are placed to point and group all the Z80 instructions or an UPI call sequence necessary to execute a particular task that is commented.

Two or four digit hexadecimal (hex) numbers will be followed by a capital H, instead of a preceding dollar sign ($).

A one or more digit number not followed by H will be a normal decimal number.

End of the Series Startup document
MCM Design
July 2019